Developer CD Series 2000 November: Tool Chest/Dev.CD Nov 00 TC Disk 1.toast/Tool Chest/Testing & Debugging/Debuggers & dcmds/MacsBug 6.6/Building dcmds/dcmd Includes/Dcmd.a

Text File | 1999-10-20 | 9.8 KB | 357 lines | [TEXT/MPS ]

;
;    File:        dcmd.a
;
;    Contains:    MacsBug debugger command interface.
;
;    Version:    Technology:    MacsBug
;                Release:    MacsBug 6.6
;
;    Copyright:    © 1988, 1994-1999, 1999 by Apple Computer, Inc., All Rights Reserved.
;
;    Bugs?:        For bug reports, consult the following page on
;                the World Wide Web:
;
;                    http://developer.apple.com/bugreporter/
;
;
    IF &TYPE('__DCMD__') = 'UNDEFINED' THEN
__DCMD__ SET 1

    IF &TYPE('__MACTYPES__') = 'UNDEFINED' THEN
    include 'MacTypes.a'
    ENDIF
    IF &TYPE('__MACHINEEXCEPTIONS__') = 'UNDEFINED' THEN
    include 'MachineExceptions.a'
    ENDIF

;  Possible requests from the debugger to the command

dcmdInit                        EQU        0                    ; Initialize the Dcmd
dcmdDoIt                        EQU        1                    ; Normal Dcmd execution
dcmdHelp                        EQU        2                    ; Display help for Dcmd
                                                            ; Requests added to MacsBug in 6.5d10 that are only sent to format 3 or newer dcmds.
dcmdSecondaryInit                EQU        3                    ; Second time to init after all System patches have been loaded
dcmdShutdown                    EQU        4                    ; Dcmd should remove any patches (if possible)
dcmdGetInfo                        EQU        5                    ; Return dcmd version and pointer to help text

;  68K register file indices into the RegisterFile.

D0Register                        EQU        0
D1Register                        EQU        1
D2Register                        EQU        2
D3Register                        EQU        3
D4Register                        EQU        4
D5Register                        EQU        5
D6Register                        EQU        6
D7Register                        EQU        7
A0Register                        EQU        8
A1Register                        EQU        9
A2Register                        EQU        10
A3Register                        EQU        11
A4Register                        EQU        12
A5Register                        EQU        13
A6Register                        EQU        14
A7Register                        EQU        15
PCRegister                        EQU        16
SRRegister                        EQU        17                    ; SR is only 16 bits and is stored in the high word

;  Heap block types

freeBlock                        EQU        0
nonrelocatableBlock                EQU        1
relocatableBlock                EQU        2

;     The format of the 68K registers passed to the dcmd.
RegisterFile            RECORD 0
elements                 ds.l    18
sizeof                     EQU *                    ; size:   $48 (72)
                        ENDR


; typedef long *                        RegisterFilePtr


;  Structure used to pass information to and from the dcmd.
dcmdBlock                RECORD 0
registerFile             ds.l    1                ; offset: $0 (0)        ;  pointer to 68K CPU register set
request                     ds.w    1                ; offset: $4 (4)        ;  what action we are requested to take
aborted                     ds.b    1                ; offset: $6 (6)        ;  Set to true if the user types a key while scrolling
pad1                     ds.b    1                ; offset: $7 (7)        ;  align to word boundary
macsBugVersion             ds.l    1                ; offset: $8 (8)        ;  version of MacsBug we are running under
maxCallback                 ds.w    1                ; offset: $C (12)        ;  maximum valid callback we can make
currentISA                 ds.b    1                ; offset: $E (14)        ;  ISA of current PC
pad2                     ds.b    1                ; offset: $F (15)        ;  align to word boundary
theException             ds.l    1                ; offset: $10 (16)        ;  Pointer to PowerPC machine state if ISA is PowerPC
requestIOBlock             ds.l    1                ; offset: $14 (20)        ;  general-purpose input/output data block pointer
sizeof                     EQU *                    ; size:   $18 (24)
                        ENDR
; typedef struct dcmdBlock *            dcmdBlockPtr


GetInfoRequestBlock        RECORD 0
usageStr                 ds        Str255            ; offset: $0 (0)
creditsStr                 ds        Str255            ; offset: $100 (256)
dcmdVersion                 ds        NumVersion        ; offset: $200 (512)
sizeof                     EQU *                    ; size:   $204 (516)
                        ENDR
; typedef struct GetInfoRequestBlock *    GetInfoRequestBlockPtr


;
;    MacsBug callback routines that can be called by the dcmd.
;


;
;    Draw the text in the Pascal string as one or more lines separated by CR's.
;    Each line causes the MacsBug display to be scrolled and the new line to be
;    drawn at the bottom. If the user types a key while scrolling then the aborted
;    flag is set telling the command to terminate immediately.
;

;
; pascal void dcmdDrawLine(ConstStr255Param str)
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdDrawLine
    ENDIF


;
;    Draw the text in the Pascal string as a continuation of the current line.
;    CR's are not given special treatment.
;

;
; pascal void dcmdDrawString(ConstStr255Param str)
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdDrawString
    ENDIF


;
;    Draw a given number of characters starting from the given pointer as a
;    continuation of the current line. CR's are not given special treatment.
;

;
; pascal void dcmdDrawText(char *text, short length)
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdDrawText
    ENDIF


;
;    Scrolls the MacsBug display up one line leaving a blank line at the bottom.
;

;
; pascal void dcmdScroll(void )
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdScroll
    ENDIF


;
;    Display the Pascal string in the command line area and wait for a key to be pressed.
;    Return TRUE if the user typed Return. All other keys return FALSE. MacsBug saves this
;    key and adds it to the command line once the current command completes. Typing any
;    key other than Return sets the aborted flag and tells the command to terminate immediately.
;

;
; pascal Boolean dcmdDrawPrompt(ConstStr255Param str)
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdDrawPrompt
    ENDIF


;
;    Get the current command line position.
;

;
; pascal short dcmdGetPosition(void )
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdGetPosition
    ENDIF


;
;    Set the current command line position. This should only be set to a value returned
;    by dcmdGetPosition.
;

;
; pascal void dcmdSetPosition(short pos)
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdSetPosition
    ENDIF


;
;    Return the next character on the command line or CR if the entire line has been scanned
;

;
; pascal short dcmdGetNextChar(void )
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdGetNextChar
    ENDIF


;
;    Return the next character on the command line or CR if the entire line has been scanned.
;    However, the current command line position is not changed.
;

;
; pascal short dcmdPeekAtNextChar(void )
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdPeekAtNextChar
    ENDIF


;
;    Copy all characters from the command line to the parameter string until a delimiter
;    is found or the end of the command line is reached. A delimiter is either a space,
;    a comma or a CR. Both single and double quoted strings are allowed on the command
;    line. However, the leading and trailing quotes must be of the same type. The parameter
;    string is returned without the quotes. This function returns the delimiter.
;

;
; pascal short dcmdGetNextParameter(Str255 str)
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdGetNextParameter
    ENDIF


;
;    Parse the command line for the next expression. All expressions are evaluated to 32 bits.
;    This function returns the delimiter after the expression. The possible delimiters are
;    space, comma and CR. Space is not treated as a delimiter in the middle of expressions,
;    unless it's before a binary '-' (minus). For instance, '1 + 2' will return a value of 3
;    and the delimiter will be the char following the 2. '1 - 2' will return a value of 1
;    and the delimeter is the space character before the '-'. This is done so that built-in
;    commands and dcmds can properly parse '-x' options. The return parameter 'ok' tells if
;    the expression was parsed successfully as far as syntax is concerned.
;

;
; pascal short dcmdGetNextExpression(long *value, Boolean *ok)
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdGetNextExpression
    ENDIF


;
;    Copy the break message MacsBug displayed the last time it was entered into str.
;    This may contain multiple lines separated by CR's.
;

;
; pascal void dcmdGetBreakMessage(Str255 str)
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdGetBreakMessage
    ENDIF


;
;    Return a symbolic representation for address in str. If no symbol can be found
;    then an empty string is returned. The format of the symbol returned is Name+00000.
;

;
; pascal void dcmdGetNameAndOffset(long address, Str255 str)
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdGetNameAndOffset
    ENDIF


;
;    Return the trap name for the trap number. If no symbol can be found
;    then an empty string is returned.
;

;
; pascal void dcmdGetTrapName(short trapNumber, Str255 trapName)
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdGetTrapName
    ENDIF


;
;    Return a pointer the macro name for the given value. If no macro can be found
;    then a nil is returned.
;

;
; pascal StringPtr dcmdGetMacroName(long value)
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdGetMacroName
    ENDIF


;
;    When a debugger command is called, the debugger's world (low memory) is installed.
;    Commands that want to reference the user's world can swap back and forth between the
;    two worlds by making this call. This procedure does nothing in MacsBug; there is no
;    distinction between user and debugger worlds. It is included to support other
;    debuggers that might want to take advantage of it.
;

;
; pascal void dcmdSwapWorlds(void )
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdSwapWorlds
    ENDIF


;
;    Toggle between the user and debugger displays. The first call restores the user's actual screen.
;    The second call restores the debugger's screen.
;

;
; pascal void dcmdSwapScreens(void )
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdSwapScreens
    ENDIF


;
;    Walk through the blocks in the current heap, calling DoThis for each block.
;    The blockAddress and blockLength pertain to the data in the heap block, not including
;    the block header. The addrOfMasterPtr is the master pointer's location in the heap,
;    not the value of the master ptr. The blockType is defined by the constants freeBlock,
;    nonrelocatableBlock and relocatableBlock. The booleans locked, purgeable and resource
;    reflect the state of the block.
;

;
; pascal void dcmdForAllHeapBlocks(DoThisPtr DoThis)
;
    IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
        IMPORT_CFM_FUNCTION dcmdForAllHeapBlocks
    ENDIF

    ENDIF ; __DCMD__